﻿/**
 * The server-side NetConnection class lets you create a two-way connection between a Flash Media Server
 * application instance and an application server, another Flash Media Server, or another Flash Media Server
 * application instance on the same server. You can use NetConnection objects to create powerful applications;
 * for example, you can get weather information from an application server or share an application load with 
 * other servers that are running Flash Media Server or application instances. 
 * 
 * @author waneck
 */

package asc.net;

extern class NetConnection 
{
	static inline function __init__():Void untyped
	{
		__js__("asc.net.NetConnection = NetConnection");
	}
	
	/**
	 * Read-only; a boolean value indicating whether a connection has been made. It is set to true if there is a 
	 * connection to the server. It’s a good idea to check this property value in an onStatus() callback function.
	 * This property is always true for AMF connections to application servers. 
	 */
	var isConnected(default, null):Bool;
	
	/**
	 * The Action Message Format (AMF) version used to pass binary data between two servers. The possible values are 3
	 * (ActionScript 3.0 format) and 0 (ActionScript 1.0 and ActionScript 2.0 format). The default value is 3. When Flash
	 * Media Server acts as a client trying to connect to another server, the encoding of the client should match the 
	 * encoding of the remote server. 
	 */
	var objectEncoding:Int;
	
	/**
	 * Read-only; a string indicating the URI parameter of the NetConnection.connect() method.
	 * This property is set to null before a call to NetConnection.connect() or after a call to NetConnection.close().
	 */
	var uri(default, null):String;

	public function new():Void;
	
	/**
	 * Adds a context header to the Action Message Format (AMF) packet structure. This header is sent with
	 * every future AMF packet. If you call addHeader() by using the same name, the new header replaces the
	 * existing header, and the new header persists for the duration of the NetConnection object. To remove
	 * a header, call addHeader() and pass it the name of the header to remove and an undefined object. 
	 * 
	 * @param	name			A string; identifies the header and the ActionScript object data associated with it.
	 * @param	mustUnderstand	A boolean; true indicates that the server must understand and process this header
	 * 							before it handles any of the following headers or messages.
	 * @param	object			An Object.
	 * 
	 * @example
	 * 
	 * The following example creates a new NetConnection instance, nc, and connects to an application at web server
	 * www.foo.com that is listening at port 1929. This application dispatches the service /blag/SomeCoolService. The
	 * last line of code adds a header called foo.
	 * 
	 * nc=new NetConnection(); 
	 * nc.connect("http://www.foo.com:1929/blag/SomeCoolService"); 
	 * nc.addHeader("foo", true, new Foo());
	 * 
	 */
	function addHeader(name:String, mustUnderstand:Bool, object:Dynamic):Void;
	
	/**
	 * Invokes a command or method on another Flash Media Server or an application server to which the application 
	 * instance is connected. The NetConnection.call() method on the server works the same way as the NetConnection.call()
	 * method on the client: it invokes a command on a remote server.
	 * 
	 * @param	methodName	A string indicating a method specified in the form "[objectPath/]method". For example, 
	 * 						the someObj/doSomething command tells the remote server to invoke the clientObj.someObj.doSomething() 
	 * 						method, with all the p1, ..., pN parameters. If the object path is missing, clientObj.doSomething()
	 * 						is invoked on the remote server.
	 * @param	?resultObj	An Object. This optional parameter is used to handle return values from the server. The result object
	 * 						can be any object that you defined and can have two defined methods to handle the returned result: 
	 * 						onResult() and onStatus(). If an error is returned as the result, onStatus()  is invoked; otherwise,
	 * 						onResult() is invoked.
	 * @param	?p1...?p6	Optional parameters that can be of any ActionScript type, including a reference to another ActionScript
	 * 						object. These parameters are passed to the methodName parameter when the method is executed on the
	 * 						remote application server.
	 * @return	For RTMP connections, returns a boolean value of true  if a call to methodName is sent to the client;
	 * 			otherwise, false. For application server connections, it always returns true.
	 */
	function call(methodName:String, ?resultObj: { onStatus:Dynamic->Void, onResult:Dynamic->Void }, ?p1:Dynamic, ?p2:Dynamic, ?p3:Dynamic, ?p4:Dynamic, ?p5:Dynamic, ?p6:Dynamic):Bool;
	
	/**
	 * Closes the connection with the server. After you close the connection, you can reuse the NetConnection instance
	 * and reconnect to an old application or connect to a new one. 
	 */
	function close():Void;
	
	/**
	 * Connects to another Flash Media Server or to a Flash Remoting server such as Adobe® ColdFusion®.
	 * 
	 * Call NetConnection.connect() to connect over HTTP to an application server running a Flash Remoting gateway.
	 * Call NetConnection.connect() to connect to another Flash Media Server for sharing audio, video, and data over 
	 * one of the following versions of RTMP: RTMP, RTMPS
	 * 
	 * It is good practice to write an application.onStatus()  callback function and check the NetConnection.isConnected 
	 * property for RTMP connections to see whether a successful connection was made. For Action Message Format 
	 * (AMF) connections, check NetConnection.onStatus().
	 * 
	 * @param	URI			A string indicating a URI to connect to. URI has the following format: 
	 * 						[protocol://]host[:port]/appName[/instanceName]
	 * @param	?p1...?p6	Optional parameters that can be of any ActionScript type, including references to other 
	 * 						ActionScript objects. These parameters are sent as connection parameters to the 
	 * 						application.onConnect()  event handler for RTMP connections. For AMF connections to application
	 * 						servers, RTMP parameters are ignored.
	 * @return	For RTMP connections, a boolean value of true for success; otherwise, false. For AMF connections to 
	 * 			application servers, true is always returned.
	 */
	function connect(URI:String, ?p1:Dynamic, ?p2:Dynamic, ?p3:Dynamic, ?p4:Dynamic, ?p5:Dynamic, ?p6:Dynamic):Bool;
	
	/**
	 * Invoked every time the status of the NetConnection object changes. For example, if the connection with the server
	 * is lost in an RTMP connection, the NetConnection.isConnected property is set to false, and NetConnection.onStatus()
	 * is invoked with a status message of NetConnection.Connect.Closed. For AMF connections, NetConnection.onStatus() 
	 * is used only to indicate a failed connection. Use this event handler to check for connectivity.
	 * 
	 * @param	infoObject	An Object with properties that provide information about the status of a NetConnection
	 * 				information object. This parameter is optional, but it is usually used. The NetConnection information
	 * 				object contains the following properties: 
	 * 
	 * @see 	asc.enums.NetConnectionStatus
	 */
	dynamic function onStatus(infoObject: { code:String, level:String, description:String } ):Void;
}